Java Basic API
按照VoIP&IM Mobile SDK API的封装原则，Java Basic API接口可划分为：基本功能接口、通话功能接口和对讲功能接口等三个功能模块。
下面分别说明各接口功能模块的具体使用方法。
基本功能接口
基本功能接口主要提供应用管理、即时消息和群组管理功能。
4.1.1 应用/账号管理
初始化SDK库
| 函数原型 | boolean initialize (Context context, String appKey, EventListener listener); |
|---|---|
| 参数 | context: Android上下文引用。 appKey：字符串，用于标识第三方APP的授权码。 listener：SDK事件回调接口。 |
| 返回值 | 布尔型－客户端初始化结果，成功返回true，失败返回false。 |
| 说明 | 初始化和启动SDK客户端模块。 注：APP授权码需预先申请。 |
| 示例 |
|
绑定APP用户账号
| 函数原型 | String bindAppAccount (String appAccount, boolean mustAuth,String callerName, String callerNumber); |
|---|---|
| 参数 | appAccount：字符串，App帐号（可采用手机号码作为App帐号，但是也允许使用Email或其它帐号形式）。 mustAuth：布尔值，此参数为true时，SDK强制到服务器进行远程身份验证，否则只在本地数据库进行验证。这样，由APP自己来决定是否进行互踢，或快速登录。 callerName：字符串，用户的本地昵称，主要用于outbound call时设置主叫的名字； callerNumber：字符串，用户的电话号码，主要用于outbound call时设置主叫的电话号码，需要标准E.164格式。 |
| 返回值 | 字符串－与此帐号绑定的FreePP号码。如果返回值为NULL，则为AppKey不合法，或者绑定失败，具体需要参考错误码表。 |
| 说明 | 验证App的合法性，并分配或绑定FreePP号码，并登录FreePP系统。此外，如果存在callerName和callerNumber则会保存到SDK中，并在发起outbound call时作为主叫的名字和号码发送到PSTN/GSM网络。 注： SDK初次绑定FreePP ID时需要通过访问服务器来完成，因此APP需检查网络是否正常。 |
| 示例 |
|
登出当前绑定的APP账号
| 函数原型 | int logoutAppAccount(); |
|---|---|
| 参数 | 无 |
| 返回值 | 整型，如果没有错误时，则返回0。 -15：FreePP SDK未初始化或绑定成功。 |
| 说明 | 重置当前帐号，清除本地的账号记录和缓存的消息。 注：SDK的本地数据库文件暂时不做删除，以方便后续再次使用APP帐号绑定登录 |
| 示例 |
|
查询FreePP号码
| 函数原型 | Map |
|---|---|
| 参数 | appAccounts：字符串数组，目标用户的APP帐号列表。 |
| 返回值 | Map类型－与App帐号对应的FreePP号码列表。如果出现错误则返回NULL，多个账号重复则Map中key只有一个。 |
| 说明 | 按照APP账号名称查询指定用户的FreePP号码。 |
| 示例 |
|
查询APP账号
| 函数原型 | Map |
|---|---|
| 参数 | freeppIds：字符串数组，目标用户的FreePPID列表。 |
| 返回值 | Map类型－与FreePP号码列表对应的APP帐号列表。如果出现错误，或者对方没有安装FreePP，返回NULL，多个账号重复则Map中key只有一个。 |
| 说明 | 根据FreePP号码查询指定用户的APP账号名称。 注：建议APP应缓存查询结果，以减少与SDK/服务器的交互，降低服务器的运营压力 |
| 示例 |
|
修改SDK配置参数
| 函数原型 | int setParameter(String name, String value); |
|---|---|
| 参数 | name：字符串，参数名称。 value：字符串，参数值。 |
| 返回值 | 整型，0-设置成功，错误码参考错误码表。 |
| 说明 | 设置SDK内部的配置参数。 注：目前支持的配置参数参见附录1。 |
| 示例 |
|
读取SDK配置参数
| 函数原型 | String getParameter(String name); |
|---|---|
| 参数 | name：字符串，参数名称。 |
| 返回值 | 字符串－参数值。如果参数不存在，则返回空字符串。 |
| 说明 | 读取SDK内部的配置参数。 注：目前支持的配置参数参见附录1。 |
| 示例 |
|
追踪错误代码
| 函数原型 | int getLastErrorCode(); |
|---|---|
| 参数 | 无 |
| 返回值 | 整型－如果没有错误时，则返回0。（错误代码定义参见附录2） |
| 说明 | 读取最后一次接口调用失败的错误码。 注：此接口为线程安全的，即保证不同线程最后一次错误是独立保存的，如果调用此接口后，SDK即会清除当前线程的错误码。 |
| 示例 |
|
响应系统事件
| 函数原型 | CALLBACK void onSystemEvent(int eventType, Object dataOjbect); |
|---|---|
| 参数 | eventType：整型，事件类型，包含：1=当前用户被踢出；对应的 data 为 NULL； dataOjbect：对应的数据对象。不同的事件类型，有不同的对象，可以为 NULL。 |
| 返回值 | 无 |
| 说明 | 向APP推送与当前用户帐号有关的系统事件。 |
| 示例 |
|
获取计费信息
| 函数原型 | String getUserBalance(String peer); |
|---|---|
| 参数 | peer：字符串，输入参数，接收本端消息或者通话的接收端（不同的对端身份计费规则可能不同） |
| 返回值 | 返回目前本端的点数及对应的本端与对端支持的服务 |
| 说明 | 获取目前本端用户的点数等信息,如：{"balance":xxx, "flags":xxx} balance：返回目前所剩的点数 flags：返回目前所剩的点数对应的本端与对端支持的服务。是一个位值，0：No，1：YES，位的含义如下： bit0 – 允许发文本消息 bit1 – 允许发图片消息 bit2 – 允许发语音消息 bit3 – 允许语音通话 bit4 – 允许视频通话 bit5 - 显示余额不足警告 |
| 示例 |
|
更新计费信息事件
| 函数原型 | CALLBACK Void onUpdateBalanceEvent(String peer, int balance, int flags); |
|---|---|
| 参数 | peer：字符串，接收本端消息或者通话的接收端（不同的对端身份计费规则可能不同） balance：整型，本端目前的点数； flags：整型，根据目前所剩的点数本端与对端支持的服务。是一个位值，0：No，1：YES，位的含义如下： bit0 – 允许发文本消息 bit1 – 允许发图片消息 bit2 – 允许发语音消息 bit3 – 允许语音通话 bit4 – 允许视频通话 bit5 - 显示余额不足警告 |
| 返回值 | 无 |
| 说明 | 向APP上报目前的点数情况。 注：当flags为32时，即bit5为1，其他位都为0，该次上报事件是一个余额不足的警告 |
| 示例 |
|
4.1.2 即时消息
发送一对一消息
| 函数原型 | String sendMessage(String dstFreePPID, String mimeType, StringtextContent, String filePath,String messageID); |
|---|---|
| 参数 | dstFreePPID：字符串，目标用户的FreePP号码。 mimeType：字符串，多媒体消息的类型，例如：”text/plain”。 textContent：字符串，文本消息的内容，其格式根mimeType来区分。如果为text/plain则为纯文本字符串；如果为application/json则为JSON字符串。 filePath：字符串，二进制文件的本地文件路径。 messageID：字符串，如果是重试发送消息的消息ID。 |
| 返回值 | 字符串-消息的ID。如果出现错误返回NULL。(注：消息ID格式为：“FreePP号码-Unix时间戳（秒）-两位序号-Unix时间戳（发送时间）”。 |
| 说明 | 向指定的用户异步地发送一对一的多媒体消息。 注：此接口为异步接口，可触发回调函数包括onSendMessageEvent和onUploadAttacthmentProgressEvent。 如果messageID参数有值，则SDK会判断此消息ID是否有效。对于有效的消息，SDK会重新发送此消息ID对应的消息内容，并返回此Message ID；对于无效的消息，SDK则直接返回为NULL。 |
| 示例 |
|
发送群组消息
| 函数原型 | String sendGroupMessage(String dstGroupID, String mimeType, StringtextContent, String filePath,String messageID); |
|---|---|
| 参数 | dstGroupID：字符串，目标群组的唯一标识符。 mimeType：字符串，多媒体消息的类型。 textContent：字符串，文本消息的内容，其格式根据mimeType来区分。 filePath：字符串，二进制文件的本地文件路径。 messageID：字符串，如果是重试发送消息的消息ID。 |
| 返回值 | 字符串-消息的ID。如果出现错误返回NULL。 注：消息ID格式为：“FreePP号码-Unix时间戳（秒）-两位序号-Unix时间戳（发送时间）”。 |
| 说明 | 向指定的群组异步地发送一对多的多媒体消息。 注：此接口为异步接口，可触发回调函数OnSendMessageEvent和onUploadAttacthmentProgressEvent。 如果messageID参数有值，则SDK会判断此消息ID是否有效。对于有效的消息，SDK会重新发送此消息ID对应的消息内容，并返回此Message ID；对于无效的消息，SDK则直接返回为NULL。 |
| 示例 |
|
清除缓存的消息
| 函数原型 | void clearMessage(String[]messageIDArray); |
|---|---|
| 参数 | messageIDArray：字符串数组，被释放的消息的标识符。如果此参数为空，则默认清除所有缓存。 |
| 返回值 | 无 |
| 说明 | 清除SDK内部存储的消息记录。 注：APP在接收或发送消息成功后，可调用此函数以清除SDK中的缓存记录。 |
| 示例 |
|
检查新消息
| 函数原型 | void checkNewMessage(); |
|---|---|
| 参数 | 无 |
| 返回值 | 无 |
| 说明 | 客户端主动到服务器上检查和下载新消息。 注：此接口为异步接口，可触发回调函数onReceiveMessageEvent。 |
| 示例 |
|
响应消息发送结果
| 函数原型 | CALLBACK void onSendMessageEvent(String messageID,int sendResult); |
|---|---|
| 参数 | messageID：字符串，发送消息的唯一标识ID。 sendResult：整型，发送消息的结果。0=成功，发送失败参照错误码表。 |
| 返回值 | 无 |
| 说明 | APP通过此接口获得一对一和群聊消息消息的发送状态。 注：对于发送文本消息和文件消息，均使用此回调函数来获得发送结果；对于文件型消息，还可以通过onUploadMessageAttachmentProgressEvent回调函数获取文件传输的进度。 |
| 示例 |
|
获取新消息
| 函数原型 | CALLBACK void onReceivedMessageEvent(int msgType, Message message); |
|---|---|
| 参数 | msgType：整型，消息类型，取值为 0= 一对一消息/群组消息类型； 1 = 加入群组通知类型； 2 = 离开群组类型； 3 = 消息接收状态通知类型 message: 消息的基类，上层APP可以根据msgType对此对象进行强转。 |
| 返回值 | 无 |
| 说明 | App通过此回调函数统一地接收一对一或群组消息。 注：对于发送文本消息和文件消息，均使用此回调函数来获得发送结果；对于文件型消息，还可以通过onUploadMessageAttachmentProgressEvent回调函数获取文件传输的进度。 注：如果余额不足，发送消息失败，则上报原因为ERROR_BANNER_USER（-13） |
| 示例 |
|
下载消息附件
| 函数原型 | int downloadMessageAttachment(String messageID, int isThumbnail, String filePath); |
|---|---|
| 参数 | messageID：字符串，要求下载的消息的唯一标识。 isThumbnail：整型，是否要下载缩略图，1-下载缩略图，0-下载原图，非图片类型无效参数。 filePath：字符串，下载到本地的文件路径，包含文件的名称。 |
| 返回值 | 整型－0：加入到下载队列中，其他错误码参考错误码表。 |
| 说明 | 下载指定消息中的附件（多媒体文件）。 注：App首先通过OnReceivedMessageEvent接口获得消息通知，然后再调用downloadMessageAttachment接口下载消息中的附件。 注：此接口为异步接口，可触发回调函数onDownloadMessageAttachmentProgressEvent和onDownloadMessageAttachmentEvent。 |
| 示例 |
|
响应消息附件的下载结果
| 函数原型 | CALLBACK void onDownloadMessageAttachmentEvent(String messageID,int downloadResult); |
|---|---|
| 参数 | messageID：字符串，下载消息的唯一标识ID。 downloadResult：整型，下载消息的结果。0=成功，下载失败参照附录2。 |
| 返回值 | 无 |
| 说明 | APP通过此接口更新消息附件的下载状态。 |
| 示例 |
|
响应消息附件的上传进度
| 函数原型 | CALLBACK void onUploadMessageAttachmentProgressEvent(String messageID, int uploadProgress); |
|---|---|
| 参数 | messageID：字符串，消息的唯一标识ID。 uploadProgress：整型，当前上传文件进度的百分比。 |
| 返回值 | 无 |
| 说明 | APP可通过此回调函数更新文件上传的进度提示。 注：文件上传由sendMessage或sendGroupMessage接口发起。 |
| 示例 |
|
响应消息附件的下载进度
| 函数原型 | CALLBACK void onDownloadMessageAttachmentProgressEvent(String messageID, int downloadProgress); |
|---|---|
| 参数 | messageID：字符串，消息的唯一标识ID； downloadProgress：整型，当前下载文件进度的百分比 |
| 返回值 | 无 |
| 说明 | APP可通过此回调函数更新文件下载的进度提示。 |
| 示例 |
|
发送消息的接收状态
| 函数原型 | int reportMessageStatus(String dstFreePPID, String messageID, int status); |
|---|---|
| 参数 | dstFreePPID：字符串，目标用户的FreePP号码。 messageID：字符串，消息的唯一标识ID。 status：整型，发送消息接收状态通知的类型，包括：1 = 已送达；2 = 已读。 |
| 返回值 | 整型 – 是否发送成功。0 = 已加入发送队列发送；-1 = 无网络无法发送 |
| 说明 | 发送消息接收状态通知，包括消息的送达和已读通知。 注：消息接收状态的通知为非可靠传输，不保证100%送达。 |
| 示例 |
|
4.1.3 群组管理
创建消息群组
| 函数原型 | String createGroupChat(String groupName, String[]memberArray); |
|---|---|
| 参数 | groupName：字符串，创建群组的主题。 memberArray：字符串数组，群组成员的FreePP号码列表。 |
| 返回值 | 字符串－服务器分配的群组ID。如果出现错误，则返回NULL。 |
| 说明 | 创建一个消息群组。 |
| 示例 |
|
邀请联系人加入消息群组
| 函数原型 | int joinGroupChat(String groupID, String[]memberArray); |
|---|---|
| 参数 | groupID：字符串，创建群组时返回的群组ID。 memberArray：字符串数组，邀请群组成员的FreePP ID数组。 |
| 返回值 | 整型-加入群组的结果。0=成功，其它参见附录2 |
| 说明 | 邀请用户加入指定的消息群组，被邀请的客户端会以即时消息的形式收到邀请通知。 |
| 示例 |
|
退出消息群组
| 函数原型 | int leaveGroupChat(String groupID, String[]memberArray); |
|---|---|
| 参数 | groupID：字符串，群组的唯一标识ID。 memberArray：字符串数组，被踢出群组成员的FreePP ID数组。 |
| 返回值 | 整型–离开群组的结果。0=成功，其它参见附录2 |
| 说明 | 退出指定的消息群组。 |
| 示例 |
|
获取群组信息
| 函数原型 | Group getGroupChatInfo(String groupID); |
|---|---|
| 参数 | groupID：字符串，群组的唯一标识ID。 |
| 返回值 | 群组对象（ Group ），包含以下属性： m_groupId：字符串，群组唯一标识； m_owner：字符串，群创建者的FreePP号码； m_memberList：字符串集合，群成员的FreePP号码； m_createTime: 长整型，创建群组的时间； m_groupName：字符串，群名称或主题； |
| 说明 | 获得指定群组的信息。 |
| 示例 |
|
通话功能接口
通话功能接口主要提供一对一语音或视频通话、语音会议、视频会议和媒体I/O设备（麦克风、扬声器和摄像头）控制等功能。
4.2.1 通话/会议控制
发起一对一的语音/视频通话呼叫
| 函数原型 | String makeCall(String dstID,int media); |
|---|---|
| 参数 | dstID：字符串，被叫用户的FreePP号码。 media：整型，通话的媒体类型。取值为 1=语音通话； 2=视频通话； |
| 返回值 | 字符串－通话的会话标识符（call-id）。 |
| 说明 | 发起一对一的，免费的FreePP语音或视频通话。 注：此接口为异步接口，可触发回调函数onCallStateEvent。APP可根据此函数的返回值（call-id），在回调函数中匹配相应的通话状态通知。 |
| 示例 |
|
发起节费电话呼叫
| 函数原型 | String makeOutboundCall (Stringphone, String via); |
|---|---|
| 参数 | phone：字符串，被叫电话号码。 via：Outbound路由码。 |
| 返回值 | 字符串－通话的会话标识符（call-id）。 |
| 说明 | 发起一对一的，节费的outbound语音通话呼叫。 注：此接口为异步接口，可触发回调函数onCallStateEvent。APP可根据此函数的返回值（call-id），在回调函数中匹配相应的通话状态通知。 |
| 示例 |
|
发起语音或视频会议
| 函数原型 | String joinConference(String[] dstIDs, int media,String atRoom, String[] phones, String via); |
|---|---|
| 参数 | dstIDs：字符串数组，与会者的FreePP号码。 media：整型，会议的媒体类型。3=语音会议，4=视频会议 atRoom：字符串，会议室的FreePP号码。如果会议室号码为用户本身的FreePP号码，则采用客户端混音方式；否则采用服务器混音方式。 phones：字符串数组，与会者的电话号码。 via：字符串，Outbound路由码。 |
| 返回值 | 字符串－会议的会话标识符（conference-id）。 |
| 说明 | 发起语音或视频会议呼叫并邀请与会者参加会议。 注：此接口为异步接口，可触发回调函数onConferenceStateEvent。APP可根据此函数的返回值（call-id），在回调函数中匹配相应的通话状态通知。 注：对于采用服务器混音的会议，APP需预先申请会议室号码。此外，针对同一个会议室，此函数可以被多次调用，以邀请不同的与会者加入同一个会议。 |
| 示例 |
|
结束一对一通话
| 函数原型 | int hangupCall(String callId); |
|---|---|
| 参数 | callId：字符串，通话的会话标识符，一般由makeCall/makeOutboundCall或onReceivedCall函数返回。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2. |
| 说明 | 结束指定的一对一通话（主叫和被叫均可调用此函数）。 注：此接口为异步接口，可触发回调函数onCallStateEvent。APP可根据此函数的返回值（call-id），在回调函数中匹配相应的通话状态通知。 注：如果是一个callid，则挂断当前的一对一通话；如果是一个conferenceid，则挂断本地该与会者与会议室的通话，退出该会议室 |
| 示例 |
|
结束或退出会议
| 函数原型 | int hangupConference(String conferenceID); |
|---|---|
| 参数 | conferenceID：字符串，会议的标识符，一般由joinConference函数返回。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2. |
| 说明 | 结束指定的会议。 注：对于客户端混音的会议，发起会议的主持人调用此函数时，会挂断所有与会者，而与会者调用此函数时仅挂断自己；对于服务器混音的会议，任何与会者调用此函数，都会挂断所有与会者 |
| 示例 |
|
接听通话请求
| 函数原型 | int answerCall(String callID); |
|---|---|
| 参数 | callID：字符串，通话的会话标识符，一般由onReceivedCall回调函数返回。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2. |
| 说明 | 被叫用户接听指定的来电请求。 注：在进行通话时，被叫用户会收到onReceiveCall通知和来电请求的callID。如果用户接听此来电，则APP需要调用此函数；如果用户拒绝接听来电，则APP需调用hangupCall函数拒绝来电。 注：此接口为异步接口，可触发回调函数onCallStateEvent。APP可根据通话标识符，在回调函数中匹配相应的此通话的状态通知。 |
| 示例 |
|
通话保持或恢复
| 函数原型 | int holdCall(String callID, int hold); |
|---|---|
| 参数 | callID：字符串，通话的会话标识符。 hold：整型，保持(1)或恢复(0)通话。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2. |
| 说明 | 保持或恢复通话。 |
| 示例 |
|
通话静音或取消静音
| 函数原型 | int muteCall(String callID, int mute); |
|---|---|
| 参数 | callID：字符串，通话的会话标识符或者会议室标识符 mute：整型，麦克风静音(1)或取消静音(0)。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2. |
| 说明 | 麦克风（或会议室主持人）静音或取消静音。 |
| 示例 |
|
发送DTMF拨号音
| 函数原型 | int sendDTMF(String callID, String digit, int time, int mode); |
|---|---|
| 参数 | callID：字符串，通话的会话标识符。 digit：字符串，所要发送的二次拨号数字。 time：整形，发送多个按键数字时的时间间隔，单位:ms(注：若只发送一个数字，则此参数可为0)。 mode：整形，DTMF信号传输模式。 |
| 返回值 | 整型，操作是否成功。0=成功，其它=参见附录2. |
| 说明 | 发送DTMF拨号音，完成二次拨号。 |
| 示例 |
|
选择视频会议画面
| 函数原型 | int subConferenceVideo(String pubID); |
|---|---|
| 参数 | pubID：字符串，所要观看的与会者的FreePP号码。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | APP可通过此接口为视频会议中的参与者(包括主持人和与会者)选择所观看的视频画面。 注：SDK采用出版/订阅模型实现视频画面选择。每个与会者可以订阅自己想观看的视频画面。 |
| 示例 |
|
查询会议中的所有与会者
| 函数原型 | int listConference(String conferenceID); |
|---|---|
| 参数 | conferenceID：字符串，会议的通话标识符，一般由joinConefernce或onReceiveCall函数获得。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | APP可通过此接口请求更新会议室的与会者列表。对于主持人而言，conferenceID为会议室号码；对于与会者而言，conferenceID为空。 注：此接口为异步接口，可触发回调函数onConferenceStateEvent。APP可通过回调函数获得与会者的状态和信息。 |
| 示例 |
|
会议与会者控制
| 函数原型 | int ctrlConference(String conferenceID, int withAction, String toParticipant); |
|---|---|
| 参数 | conferenceID：字符串，会议的通话标识符，一般由joinConefernce或onReceiveCall函数获得。 withAction：整型，对与会者执行的操作，取值为 0=踢出； 1=静音； 2=取消静音。 toParticipant：字符串，被操作的与会者的FreePP号码。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | APP通过此接口可控制会议中的与会者的状态。 注：此接口为异步接口，可触发回调函数onConferenceStateEvent。APP可通过回调函数获得与会者的更新状态。 |
| 示例 |
|
13）开始录音
| 函数原型 | int startMediaRecord (String callID, String filePath, int media,int format, int internalSec); |
|---|---|
| 参数 | callID：字符串，会话的通话标识符，一般由makeCall或onReceiveCall函数获得。 filePath：字符串，录音文件的存放路径 。 media：整形，其取值为： 1 = 音频 ； 2 = 视频（暂时不支持）。 format：整形，其取值为： 0 = mp3; 1 = avi（暂时不支持）。 internalSec：整型，自动分段时间间隔，以秒为单位, 默认为0，即不分段，>0 按时间段自动分段录音。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | 说明： filePath 一般需要写文件名，重复对同一个文件操作会clear以前写的录音数据。 |
| 示例 |
int media=1;
int format = 0;
m_filePath ="/storage/emulated/0/freeppsdk/"+ m_callId + "_"+ recordCount + ".mp3";
internalSec = 15;
startMediaRecord(m_callId, m_filePath,media,format, internalSec);
|
14）停止录音
| 函数原型 | int stopMediaRecord (String callID); |
|---|---|
| 参数 | callID：字符串，会话的通话标识符，一般由makeCall或onReceiveCall函数获得。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | |
| 示例 |
|
4.2.2 状态通知和查询
响应来电请求通知
| 函数原型 | CALLBACK void onReceiveCallEvent(String callId, long timestamp，String callerId, String callerName, int media, int callType); |
|---|---|
| 参数 | callId：字符串，通话或会议的会话标识符。 timestamp：长整型，收到NCL消息的服务器时间。 callerId：字符串，主叫用户的FreePP号码。 callerName：字符串，主叫用户的昵称或电话号码。 media：整型，通话请求的媒体类型，取值为1=语音通话；2=视频通话；3=语音会议通话；4=视频会议通话。 callType：整型，来电通知的类型，取值为1=新来电，2=未接来电。 |
| 返回值 | 无 |
| 说明 | APP通过此接口接收远端用户的来电请求。如果APP在锁屏状态，SDK会自动弹出PUSH通知；如果APP在运行状态，则由APP决定是否显示来电通知界面。 |
| 示例 |
|
响应通话状态改变通知
| 函数原型 | CALLBACK void onCallStateEvent(String callId,long timestamp， int withState, int byReason); |
|---|---|
| 参数 | callId：字符串，通话或会议的会话标识符。 timestamp：长整型，发起通话的服务器时间戳。 withState：整型，当前的通话状态，取值为 0 – IDLE（待机）； 1 – INITIATE（正在发起呼叫）； 2 – ANSWER（已接听）； 3 – HOLD（保持中）； 4 – HANGUP（已挂断）。 有关通话状态的说明可参考3.2.2节。 byReason：整型。当state为HANGUP时标识结束通话的原因，包括：被叫不在线、没有可用的网络连接、被叫忙等；当state为ANSWER时表示进入通话的途径，包括：0 - 接听电话；1 - 恢复通话。 |
| 返回值 | 无 |
| 说明 | APP通过此接口获知通话的状态发生改变。在不同的通话状态下，APP应显示不同提示，例如：1) IDLE－无；2) NITIATE－正在呼叫中(主叫)或通话建立中(被叫)；3) ANSWER-通话中；4) HOLD-通话保持中；5) HANGUP-通话结束。 注：当余额不足时，上报的挂断原因为CALL_REASON_HANGUP_NO_BALANCE（19） |
| 示例 |
|
响应会议中与会者状态改变通知
| 函数原型 | CALLBACK void onConferenceStateEvent(String conferenceId, String callId, String callerId, int withState, int byReason); |
|---|---|
| 参数 | conferenceId：字符串，会议的会话标识符。 callId：字符串，与会者的通话标识符。 calleeId：字符串，与会者的FreePP号码。 withState：整型，与会者当前的通话状态，取值为 1 – INITIATE（正在邀请）； 2 – ANSWER（已进入）； 3 – HANGUP（已离开）。 byReason：整型。当state为HANGUP时，标识结束通话的原因，包括：被叫不在线、没有可用的网络连接、被叫忙等；当state为ANSWER时表示进入通话的途径，包括：0 - 接听电话；1 - 恢复通话。 |
| 返回值 | 无 |
| 说明 | APP通过此接口获得会议中某个与会者的状态发生改变。在不同的通话状态下，APP应显示不同提示：1) INITIATE－正在呼叫中(主叫)或通话建立中(被叫)；2) ANSWER-进入会议；3) HANGUP-离开会议。 |
| 示例 |
|
响应视频通信状态改变通知
| 函数原型 | CALLBACK void onRemoteVideoStateEvent(String callId, int withState); |
|---|---|
| 参数 | callId：字符串，通话或会议的会话标识符。 withState：整型，当前的通话的远端视频状态，扩展后分高位和地位，高位是原因（_stop_video_reason），低位是state（_remote_video_state），具体值定义请参考sdk常量定义。 |
| 返回值 | 无 |
| 说明 | APP通过此接口获得视频通话中远端用户的视频发送状态的改变。在不同的视频状态下，APP可选择显示不同的界面。 |
| 示例 |
|
响应通话录音状态改变通知
| 函数原型 | CALLBACK void onRecordStateEvent (String filePath, int withState); |
|---|---|
| 参数 | filePath：字符串，录音文件路径及文件名。 withState：整型，录音状态，取值为1=开启；2=停止；3=生成MP3文件。 |
| 返回值 | 无 |
| 说明 | APP通过此接口获得通话录音状态的改变。在不同的状态下，APP可选择显示不同界面。 |
| 示例 |
|
查询通话的状态和信息
| 函数原型 | FreePPCallInfo getCallInfo(String callId); |
|---|---|
| 参数 | callId：字符串，通话或会议的会话标识符。 |
| 返回值 | FreePPCallInfo-通话的信息对象。 |
| 说明 | 获取指定通话的当前状态和详细信息，且将上述信息存放在FreePPCallInfo对象中返回。FreePPCallInfo对象包含如下属性： callId：字符串，通话或会议的会话标识符。 calleeId：字符串，对端用户的FreePP号码。 calleeName：字符串，对端用户的昵称或电话号码。 mediaType：整型，通话请求的媒体类型（语音、视频或会议）。 callState：整型，当前的通话状态，取值为： 0 - IDLE； 1 - INITIATE； 2 - ANSWER； 3 - HOLD； 4 - HANGUP。 |
| 备注 |
|
获得当前正在进行的通话列表
| 函数原型 | String[] getAllCallIDList(); |
|---|---|
| 参数 | 无 |
| 返回值 | 字符串数组－所有当前正在进行的通话的标识符（call-id）列表。 |
| 说明 | 获取当前所有呼出和呼入通话的call-id字符串的列表。 注：APP可首先调用此函数获得call-id列表，然后再调用getCallInfo函数获得通话的状态和详细信息。 |
| 示例 |
|
4.2.3 媒体I/O管理
设置视频摄像头
| 函数原型 | int setCamera(int device); |
|---|---|
| 参数 | device：整型，设备标识符，例如： 0 - 后置摄像头； 1 - 前置摄像头； -1 – 不使用摄像头。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | 设置当前视频通话所使用的摄像头。 |
| 示例 |
|
设置声音输出设备
| 函数原型 | int setAudioOutput(int device); |
|---|---|
| 参数 | device：整型，扬声器设备标识符，例如： 0 - 听筒； 1 - 扬声器； 2 - 当前连接的蓝牙耳机。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | 设置通话所使用的扬声器设备。 |
| 示例 |
|
设置视频显示设备
| 函数原型 | int setVideoDisplay(View displayRemote, View displayPreview); |
|---|---|
| 参数 | displayRemote：View对象，用于显示远端视频的窗口对象（对方的图像，根据操作系统选择对象类型）。 displayPreview：View对象，用于显示近端视频的窗口对象（自己的图像）。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | 设置视频通话中用于显示视频的窗口对象。 |
| 示例 |
|
开启本地视频发送
| 函数原型 | int startVideoSend(); |
|---|---|
| 参数 | 无 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | 开启本地视频的发送。 注：通过setParameter接口设置开启视频的模式：" auto_send_video "= 0（手动），1（自动），默认值为1，即视频通话时自动发送本地视频。 |
| 示例 |
|
停止本地视频发送
| 函数原型 | int stopVideoSend(); |
|---|---|
| 参数 | 无 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | 停止本地视频的发送，并通知对端停止视频通话。 |
| 示例 |
|
设置通话请求的回铃音
| 函数原型 | int setRingbackTone(String ringbackFilePath); |
|---|---|
| 参数 | ringbackFilePath：字符串，App层Bundle或本地文件系统中回铃音文件的存储路径。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | 设置电话呼叫的回铃音。 |
| 示例 |
|
对讲功能接口
对讲功能接口主要提供进入或退出对讲频道、请求和释放发言权等控制功能。
4.3.1 频道/发言控制
进入语音对讲频道
| 函数原型 | int enterPTTChannel(String roomID); |
|---|---|
| 参数 | roomID：字符串，频道标识符（即频道的FreePP号码）。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | 进入语音对讲频道，并自动开始收听频道中的语音。 注：语音对讲频道的号码由系统预先分配，因此不在本文档的讨论范围之内。 |
| 示例 |
|
离开语音对讲频道
| 函数原型 | int leavePTTChannel(String roomID); |
|---|---|
| 参数 | roomID：字符串，频道标识符。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | 离开语音对讲频道。 |
| 示例 |
|
请求对讲的发言权
| 函数原型 | int pushTalk(String roomID); |
|---|---|
| 参数 | roomID：字符串，频道标识符。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | 请求语音频道中的发言权。一旦获得发言权，则自动进入发言状态，并停止收听语音。 注：此接口为异步接口，可触发回调函数onPTTChannelStateEvent。APP可通过回调函数获得请求的结果。 |
| 示例 |
|
释放对讲的发言权
| 函数原型 | int releaseTalk(String roomID); |
|---|---|
| 参数 | roomID：字符串，频道标识符。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | 释放已获得的频道发言权，并恢复收听状态。 注：此接口为异步接口，可触发回调函数onPTTChannelStateEvent。APP可通过回调函数获得请求的结果。 |
| 示例 |
|
4.3.2 频道状态通知
响应语音发言状态通知
| 函数原型 | CALLBACK void onPTTChannelStateEvent(int roomID, int withState, String toParticipant, int atPosition); |
|---|---|
| 参数 | roomID：字符串，频道标识符。 withState：整型，频道的当前发言状态，取值为： 0=IDLE（当前频道空闲，没有发言者）； 1=GRANTED（本机用户获得发言权并进入发言状态）； 2=RELEASED（本机用户释放发言权并恢复收听状态）； 3= QUEUED（本机用户正在排队等待发言权）； 4=DENY（服务器拒绝本机用户的发言请求）； 6=TAKEN（频道被占用，其它用户正在发言）； 10=ENTER（用户进入频道）； 11=LEAVE（用户离开频道）。 toParticipant：字符串，当state=6时，指当前发言者的FreePP号码；当state=10/11时，指进入或离开频道的用户的FreePP号码。 atPosition：整型，当state=3时，指本机用户等待发言的排队位置。 |
| 返回值 | 整型－操作是否成功。0=成功，其它=参见附录2。 |
| 说明 | APP通过此接口获得语音对讲频道的当前状态并提示用户。 |
| 示例 |
|
工作流程
下面主要介绍APP和SDK之间的基本交互操作流程。
注：
- ① 在流程图中，黑色箭头表示模块之间的函数调用关系，蓝色箭头表示函数调用的返回结果，红色箭头表示可选的交互操作（例如：仅针对文件消息）。
- ② 流程图的具体描述中，发送端/接收端、主叫端/被叫端、主持人/与会者、发言者/收听者等角色，若无特别说明，均指APP程序。
4.4.1启动流程
APP程序在启动时，应尽早完成SDK的初始化和认证工作。APP的启动流程如下图所示。
上图中，APP和SDK的具体交互流程如下：
- 1）调用setParameter函数，设置“rootcs”参数，即服务器的入口地址；同时调用setParameter函数，设置“db_path”参数，即SDK内部数据缓存地址。
- 2）调用initialize函数，初始化SDK库和验证客户端的合法性，以及设置APP层的回调函数代理对象；
- 3）调用bindAppAccount函数，绑定APP帐号并登录FreePP系统；
- 4）进入APP主界面。
4.4.2 一对一消息流程
上图中，APP和SDK的具体交互流程如下：
- 1）发送端调用queryFreePPIDByAppAccount函数，根据用户的App账号获取目标用户的FreePP号码；
- 2）发送端调用sendMessage函数发送消息；
- 3）发送端通过onSendMessageEvent回调函数获得消息的发送结果；
- 4）如果是文件型消息，发送端可以通过onUploadMessageAttachmentProgressEvent回调函数获得文件的上传进度；
- 5）接收端通过onReceivedMessageEvent回调函数接收到消息通知；
- 6）如果是文件型消息，接收端调用downloadMessageAttachment函数下载消息中的附件；
- 7）接收端通过onDownloadMessageAttachmentProgressEvent回调函数获得文件下载的进度；
- 8）接收端通过onDownloadMessageEvent回调函数得到下载消息文件的结果。
4.4.3文件消息流程
上图中，APP和SDK的具体交互流程如下：
- 1）发送端调用queryFreePPIDByAppAccount函数，根据用户的App账号获取目标用户的FreePP号码；
- 2）发送端调用sendMessage函数发送文件消息或者文本附件消息并发送占位符消息，占位符消息的消息类型为text/plainhold，消息内容为文件信息JSON字符串；
- 3）发送端通过onSendMessageEvent回调函数获得消息的发送结果；
- 4）如果是文件型消息，发送端可以通过onUploadMessageAttachmentProgressEvent回调函数获得文件的上传进度；
- 5）接收端通过onReceivedMessageEvent回调函数接收到消息通知；
- 6）如果是文件型消息，接收端调用downloadMessageAttachment函数下载消息中的附件；如果是占位符消息，接收端可以在UI上先在消息栏中显示占位符；
- 7）接收端通过onDownloadMessageAttachmentProgressEvent回调函数获得文件下载的进度；
- 8）接收端通过onDownloadMessageEvent回调函数得到下载消息文件的结果，UI根据回调函数的消息id，从消息的hash表中查找对应的占位符消息并替换成相应的文件显示。
4.4.4 群组消息流程
上图中，APP和SDK的具体交互流程如下：
- 1）发送端调用createGroupChat函数创建群组时，或者通过onReceivedMessageEvent回调函数收到群组邀请时，获得群组ID；
- 2）发送端调用sendGroupMessage函数发送群组消息；
- 3）发送端通过onSendMessageEvent回调函数获得群组消息的发送状态；
- 4）如果是文件型消息，发送端可以通过onUploadMessageAttachmentProgressEvent回调函数获得文件的上传进度；
- 5）接收端通过onReceivedMessageEvent回调函数接收到消息通知；
- 6）如果是文件型消息，接收端调用downloadMessageAttachment函数下载消息中的附件；
- 7）接收端通过onDownloadMessageAttachmentProgressEvent回调函数获得文件下载的进度，并通过onDownloadMessageEvent回调函数得到下载消息文件的状态值。
4.4.5 基本通话流程
上图中，APP和SDK的具体交互流程如下：
- 1）主叫端调用makeCall或makeOutboundCall发起通话呼叫，并通过返回值获得通话的标识符（call-id）；
- 2）主叫端通过onCallStateEvent:INITIATE状态通知，获得通话正在建立的状态；
- 3）被叫端通过onReceiveCallEvent回调函数，接收到来电通知，并获得通话的标识符（call-id）；
- 4）被叫端调用answerCall接听来电；
- 5）被叫端通过onCallStateEvent回调函数，依次得到INITIATE和ANSWER状态；
- 6）主叫端通过onCallStateEvent:ANSWER状态通知，得知被叫端已接听电话，并进入通话状态；
- 7）无论主叫端或被叫端，均可调用hangupCall结束通话，并通过onCallStateEvent:HANGUP状态通知获知通话已结束。
4.4.6 拒接电话流程
上图中，APP和SDK的具体交互流程如下：
- 1）被叫端首先从onReceieveCallEvent回调函数中，获得通话的标识符（call-id）；
- 2）被叫端拒接来电时，直接调用hangupCall函数；
- 3）主叫端和被叫端均通过onCallStateevent:HANGUP状态通知，获知通话已被拒接。
4.4.7 呼叫保留/恢复流程
上图中，APP和SDK的具体交互流程如下（以主叫端为例）：
- 1）主叫端在通话接听后，调用holdCall:1(参数为1)函数，进入呼叫保持状态。此时，SDK既不发送，也不接收语音；
- 2）主叫端和被叫端均通过onCallStateEvent:HOLD状态通知，获知指定的通话已经被保持。注：APP负责区分谁是保持动作的发起者；
- 3）主叫端调用holdCall:0（参数为0）函数恢复通话。此时，SDK恢复语音和视频的发送及接收；
- 4）主叫端和被叫端均通过onCallStateEvent:ANSWER状态通知，获知指定的通话已经恢复。
4.4.8 音视频切换流程
上图中，APP和SDK的具体交互流程如下：
- 1）主叫端调用makeCall发起通话呼叫，并通过返回值获得通话的标识符（call-id）；
- 2）主叫端通过onCallStateEvent:INITIATE状态通知，获得通话正在建立的状态；
- 3）被叫端通过onReceiveCallEvent回调函数，接收到来电通知，并获得通话的标识符（call-id）；
- 4）被叫端调用answerCall接听来电；
- 5）被叫端通过onCallStateEvent回调函数，依次得到INITIATE和ANSWER状态；
- 6）主叫端通过onCallStateEvent:ANSWER状态通知，得知被叫端已接听电话，并进入音频通话状态；
- 7）主叫端（或被叫端）通过startVideoSend开启视频，并通过setVideoDisplay设置预览和远端视频显示窗口；
- 8）被叫端（或主叫端）通过onRemoteVideoState收到远端视频的开启事件，并通过setVideoDispaly设置预览和远端视频显示窗口，进入单方视频通话中；
- 9）被叫端（或主叫端）通过startVideoSend开启视频，显示本地预览视频；
- 10）被叫端通过onRemoteVideoState 收到远端视频的开启事件，显示远端视频，进入双方视频通话中；
- 11）主叫端（或被叫端）通过stopVideoSend停止本地视频，并通知对方关闭的原因是切换到音频，app切到音频通话界面；
- 12）被叫端（或主叫端）通过onRemoteVideoState收到远端视频的停止事件，根据原因通过stopVideoSend停止本地视频，切到音频通话界面，再次进入音频通话中；
- 13）无论主叫端或被叫端，均可调用hangupCall结束通话，并通过onCallStateEvent:HANGUP状态通知获知通话已结束。
4.4.9 基本会议流程
上图中，APP和SDK的具体交互流程如下：
- 1）主持人调用joinConeference函数，向每个与会者发送会议邀请；
- 2）主持人通过onConferenceStateEvent:INITIATE状态通知，获得每个与会者的当前状态为正在邀请；
- 3）与会者通过onReceiveCallEvent回调函数，接收到主持人发送的会议邀请并提示用户；
- 4）用户接受邀请后，与会者调用answerCall函数接受会议邀请；
- 5）主持人通过onConferenceStateEvent回调函数，获知与会者进入会议室的状态；
- 6）与会者通过onConferenceStateEvent回调函数，分别获知自己的通话状态，以及所有与会者在会议室中的状态；
- 7）主持人调用hangupConference函数结束会议时，与会者通过onConferenceStateEvent回调函数，获知会议已结束。
4.4.10 会议拒接流程
上图中，APP和SDK的具体交互流程如下：
- 1）主持人调用JoinConeference函数，向每个与会者发送会议邀请；
- 2）主持人通过onConferenceStateEvent:INITIATE状态通知，获得每个与会者的当前状态为正在邀请；
- 3）与会者通过onReceiveCallEvent回调函数，接收到主持人发送的会议邀请并提示用户；
- 4）用户拒接邀请后，与会者调用HangupCall函数拒接会议邀请；
- 5）主持人通过onConferenceStateEvent回调函数，获知与会者离开会议室的状态；
- 6）与会者通过onConferenceStateEvent回调函数，分别获知自己的通话状态，以及所有与会者在会议室中的状态。
4.4.11 会议控制流程
上图中，所有与会者都进入会议后，APP和SDK的具体交互流程如下：
- 1）与会者A调用CtrlConeference:B函数，踢出与会者B，并通过onConferenceStateEvent:HANGUP通知提示与会者B离开会议室；
- 2）与会者B及其他与会者通过onConferenceStateEvent: HANGUP状态通知，获知与会者B离开会议室的状态。
4.4.12视频控制流程
上图为视频会议订阅流程，所有与会者都进入会议后，APP和SDK的具体交互流程如下：
- 1）在视频会议中，无论主持人或与会者，都可以通过调用SubConferenceVideo函数，选择所要观看的与会者视频画面。（注：默认情况下，客户端混音与会者端显示主持人视频，主持人不显示远端视频；服务器混音所有与会者只显示本地视频，不显示远端视频）；
- 2）与会者可以互相订阅对方的视频；
- 3）取消视频订阅：当SubConferenceVideo:0时，取消视频订阅，远端视频无显示；
- 4）在视频通话中（包括一对一和会议），客户端可以调用StartVideoSend函数，允许发送本机视频；客户端可以调用StopVideoSend函数，停止发送本机视频。
4.4.13语音对讲流程
上图中，APP和SDK的具体交互流程如下：
- 1）发言者和收听者首先调用EnterPTTRoom函数，进入语音对讲频道；
- 2）发言者和收听者可通过onPTTStateEvent:ENTER状态通知，获知自己和其它参与者进入语音对讲频道的状态；
- 3）发言者调用PushTalk函数，向对讲频道请求发言权；
- 4）发言者通过onPTTStateEvent:GRANTED状态通知，获知已获得发言权，然后开始发言；
- 5）收听者通过onPTTStateEvent:TAKEN状态通知，获知对讲频道已被占用，并开始收听发言；
- 6）发言者调用ReleaseTalk函数，释放发言权；
- 7）发言者通过onPTTStateEvent:RELEASED状态通知，获知发言权已被释放，并重新进入收听状态；
- 8）收听者通过onPTTStateEvent:IDLE状态通知，获知对讲频道进入空闲状态；
- 9）发言者和收听者可调用LeavePTTRoom函数，退出语音对讲频道。
开发环境配置
Java版SDK提供以下文件供第三方APP开发者使用：
- Java的jar包：freeppstreamsdk.jar是包含消息SDK的语音视频通话SDK库文件。
- .so动态链接库：libVideoEngineJni.so是负责音视频通话的底层库。
- 库函数说明：FreeppSDK.java
第三方APP需要在项目工程中链接一下库文件：
- 使用通话SDK则在工程中需要增加的Library（如下图）；
- 添加freeppstreamsdk.jar到java编译路径中（如下图）；
